Document "Zigbee Groups" in ZHA integration #29316
Conversation
Add initial documentation for "Zigbee Groups" in the ZHA integration.
home-assistant
bot
added
current
Heading levels should increment by one level at a time heading-increment remark-lint
Co-authored-by: j4n-e4t <130256240+j4n-e4t@users.noreply.github.com>
Co-authored-by: j4n-e4t <130256240+j4n-e4t@users.noreply.github.com>
@j4n-e4t Thanks! I have commited your suggested changes now. |
✅ Deploy Preview for home-assistant-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
@puddly is this not better a start than not having any section about this? This is at least a beginning that others could build on. |
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
Co-authored-by: TheJulianJES <TheJulianJES@users.noreply.github.com>
|
@TheJulianJES You suggested changes have been commited now. |
WalkthroughWalkthroughThe Changes
Sequence Diagram(s) (Beta)sequenceDiagram
participant User
participant ZHA Integration
participant Zigbee Device
participant Zigbee Group
User->>ZHA Integration: Create Zigbee Group
ZHA Integration->>Zigbee Group: Add Devices to Group
User->>ZHA Integration: Bind Device to Group
ZHA Integration->>Zigbee Device: Bind to Group
Zigbee Device->>Zigbee Group: Join Group
User->>Zigbee Group: Send Command
Zigbee Group->>Zigbee Device: Relay Command
Recent review detailsConfiguration used: CodeRabbit UI Files selected for processing (1)
Additional context usedLanguageTool
Markdownlint
Additional comments not posted (1)
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
| ## Zigbee groups and binding devices | ||
|
|
||
| ZHA supports binding and unbinding. Binding is an action in Zigbee which defines relations between two Zigbee devices, specific endpoints, and cluster id. It provides a mechanism for attaching an endpoint on one Zigbee node to one or more endpoints on another Zigbee node or Zigbee group (a group of Zigbee devices). | ||
| ZHA supports Zigbee groups and binding devices to each other. These features can be used separately or combined. For example, binding a remote to a bulb or group has the benefit of faster response time and smoother control, as the remote directly controls the bound devices. | ||
|
|
||
| Binding is a "target destination" in form of a device address or group ID, endpoint, and cluster. For example, binding a Zigbee device like a remote to a Zigbee lightbulb, switch or group of lightbulbs allows direct control of the "target" device (light, switch, shade) from the "remote" Zigbee device, bypassing ZHA. This means that the remote can control the lightbulb/group of lightbulbs even when the Zigbee coordinator is not available. | ||
| Binding is only supported within the same cluster, for example, "output cluster id 6" (on/off cluster) of a remote, can be only bound to an "input cluster id 6" on the target device -- light, switch. | ||
| ### Zigbee group | ||
|
|
||
| Note that not all devices support binding as it depends on the Zigbee implementation of the device itself. Also, by default ZHA binds remotes to the coordinator, so the coordinator can receive ZCL commands from the remotes and originate zha_events. However, some remotes, for example, the Philips RWL021 can only be bound to a single destination and it is not possible to make this switch to bind to other destinations like a device or groups unless you first unbind the remote from the coordinator. After you unbind the remote from the ZHA coordinator you can then bind it directly to any other Zigbee device or a group. | ||
| A Zigbee group enables the grouping of multiple Zigbee lights, switches, and fans. This allows you to control those devices with only one command/entity. | ||
|
|
||
| Binding a remote directly to a bulb or group has the benefit of faster response time and smoother control. This greatly improves user feedback experience functions like dimming as the remote then directly dims the lightbulb and thus does not have to make the software roundtrip via the ZHA coordinator. | ||
| <div class='note'> | ||
| Note that while using a native Zigbee group instead of Home Assistant's [Group](/integrations/group/) integration can improve the visual responsiveness, the broadcast commands issued can flood the Zigbee network if issued repeatedly. | ||
| </div> | ||
|
|
||
| To create a Zigbee Group, press the "Configure" button on the ZHA integration config page. At the top, choose "Groups" and select "Create Group". Set a group name and choose which devices to include in the group. | ||
|
|
||
| The group should consist of products of the same device type (e.g. all lights, switches, or fans), and at least two devices must be added to a Zigbee group before a group entity is created. | ||
|
|
||
| ### Zigbee binding and unbinding | ||
|
|
||
| Binding is an on-device feature for Zigbee devices. It provides a mechanism for attaching an endpoint of one Zigbee device to an endpoint of another Zigbee device or to a Zigbee group. | ||
|
|
||
| For example, binding a "target destination" Zigbee device like a remote to a Zigbee light bulb, switch or group of light bulbs allows direct control of the "target" device (light, switch, shade) from the "remote" Zigbee device, bypassing ZHA. This means that the remote can control the light bulb or group even when ZHA is not active.``` | ||
|
|
||
| Note that not all devices support binding. By default, ZHA binds remotes to the coordinator, so click events are forwarded to HA. As some remotes can only be bound to a single destination, you might need to unbind the remote from the coordinator before binding it to another device or group. |
There was a problem hiding this comment.
Tip
Codebase Verification
The documentation includes some information about creating Zigbee groups and binding/unbinding devices, but it lacks detailed step-by-step instructions for these processes.
- The section on creating Zigbee groups mentions the need to press the "Configure" button, choose "Groups," and select "Create Group," but it does not provide detailed steps or screenshots.
- The section on binding and unbinding devices explains the concept and mentions the need to unbind a remote from the coordinator before binding it to another device or group, but it lacks detailed instructions on how to perform these actions.
To ensure the documentation is comprehensive and user-friendly, it should include detailed, step-by-step instructions for setting up Zigbee groups and binding/unbinding devices.
- Add detailed steps for creating Zigbee groups, including screenshots if possible.
- Add detailed steps for binding and unbinding Zigbee devices, including screenshots if possible.
Analysis chain
Ensure that the documentation on Zigbee groups and binding includes all necessary steps and considerations for setting up and managing these features effectively.
Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Verify if the documentation includes all necessary steps for setting up Zigbee groups and binding.
# Test: Search for setup steps in the documentation. Expect: Detailed steps.
rg --type markdown 'setup steps' ./source/_integrations/zha.markdown
Length of output: 70
Script:
#!/bin/bash
# Description: Verify if the documentation includes all necessary steps for setting up Zigbee groups and binding.
# Test: Search for detailed steps for creating Zigbee groups.
rg --type markdown 'create group' ./source/_integrations/zha.markdown
# Test: Search for detailed steps for binding Zigbee devices.
rg --type markdown 'binding' ./source/_integrations/zha.markdown
# Test: Search for detailed steps for unbinding Zigbee devices.
rg --type markdown 'unbind' ./source/_integrations/zha.markdown
Length of output: 2482
Tools
LanguageTool
[misspelling] ~428-~428: Possible spelling mistake found.
Context: ... ## Zigbee groups and binding devices ZHA supports Zigbee groups and binding devi...
[misspelling] ~439-~439: Possible spelling mistake found.
Context: ...up, press the "Configure" button on the ZHA integration config page. At the top, ch...
[misspelling] ~447-~447: Possible spelling mistake found.
Context: ...m the "remote" Zigbee device, bypassing ZHA. This means that the remote can control...
[misspelling] ~447-~447: Possible spelling mistake found.
Context: ...ntrol the light bulb or group even when ZHA is not active.``` Note that not all de...
[misspelling] ~449-~449: Possible spelling mistake found.
Context: ...ll devices support binding. By default, ZHA binds remotes to the coordinator, so cl...
Proposed change
Add initial documentation for "Zigbee Groups" in the ZHA integration (which was missing documentation about "Zigbee Group").
Type of change
currentbranch).currentbranch).nextbranch).nextbranch).Additional information
Checklist
currentbranch.Summary by CodeRabbit